MD5 exporter

MD5 Importer/Exporter for Blender 2.72+

• MD5 Importer/Exporter for Blender 2.72+
  • Installation
  • Before You Begin
  • Usage
    • Importing MD5 Meshes
    • Importing MD5 Animations
    • Exporting MD5 Meshes
    • Exporting Individual MD5 Animations
    • Batch Export of MD5 Meshes and Animations
    • Handling Shaders
  • Export Errors

This import and export script provides the following functionality:

Import:

• Individual .md5mesh file
• Individual .md5anim file

Export:

• Individual .md5mesh file
• Individual .md5anim file
• Batch MD5 export: .md5mesh and .md5anim at once

Versions prior to 0.8 featured only export but no import.

The exporter is compatible with Blender 2.72 and later (export should work with versions as old as 2.66). It was made for use in the Arx: End of Sun project, and built around the workflow used by the project team. In a nutshell, the workflow is as follows:

• Only a subset of the armature's bones are intended for export.
• Constraints and drivers are used freely.
• The character faces positive Y.
• Care is taken to keep object transforms applied.

Installation

Important: If you had version 0.6 of the script installed, remove it before installation. For that, use the add-on's Remove button, or delete the io_scene_md5 subdirectory manually from your addons directory. For details about the addons directory location, see the Add-Ons page in the Blender wiki. The script is a single file since version 0.7 instead of two files in a subfolder.

Install this script as an add-on:

1. Open Blender's User Preferences window and go to the Add-ons tab.
2. Click Install from File and specify the downloaded io_scene_md5.zip file or the unpacked io_scene_md5.py file.
3. Enable the Import-Export: id tech 4 MD5 format addon.
4. To make your changes persistent, click Save User Settings.

Before You Begin

For export to work, indicate the bones that you want exported. For that, add them to a reserved layer in your armature. Bones that are not tagged in this way will be ignored.

To specify which layer is reserved for MD5 import/export and populate the layer, go to the Properties editor | Scene context | MD5 Setup panel. By default, layer 5 is used (5 for "MD5").

To manage the membership of your reserved layer, select your armature, switch to edit mode or pose mode, and use the following buttons in the MD5 Setup panel:

• Add Selected
• Remove Selected
• Replace with Selected
• Clear All

If you can't be bothered tracking layer membership, set the layer number to 1. All bones in Blender are members of layer 1 by default.

It is recommended that your armature and meshes have their object transformations applied before export. Otherwise, the result may not look as expected or the exporter may fail.

Usage

Importing MD5 Meshes

Click File | Import | MD5 Mesh in the main menu.

Importing MD5 Animations

1. Set the time slider to the frame you want the sequence to start at.
2. Select the armature that you want to add animation to. The armature should match the skeleton in the file you are going to import.
3. Click File | Import | MD5 Animation in the main menu.

If everything is OK, the animation sequence is added, and markers are placed in the timeline for the start ("<filename>_start") and end ("<filename>_end") of the sequence. The naming of the markers is consistent with the convention described in the Batch Export of MD5 Meshes and Animations section below.

Notes:

• The importer transfers the keys defined in the .md5anim to the fcurves of the armature's bones. If your armature is rigged with constraints, drivers and IK, and those are enabled, don't expect the resulting animations to match those in the file. However, the keys will be there, so when you disable your extra rigging features at any time, you should have a faithful representation of the animation in the file.
• For bone rotations, the importer sets keys on both the Euler and quaternion channels.

Exporting MD5 Meshes

1. Select one or more meshes that you want to export. The meshes should be associated with the same deforming armature. Any selected meshes that do not have an armature modifier will be ignored.
2. Click File | Export | MD5 Mesh in the main menu.
3. To avoid reorienting your 3D assets to face positive X, clear the Reorient option. Normally, this option should be turned on, because unlike id tech 4, Blender assumes the "forward" direction for character rigs to be positive Y.
4. If you want a different scale for your 3D assets in the resulting file, use the Scale option.
5. Specify the file path and complete the export.

Exporting Individual MD5 Animations

Individual .md5anim export uses the current playback range as the animation frame range.

1. Select one or more meshes that you want to export. The meshes should be associated with the same deforming armature. Any selected meshes that do not have an armature modifier will be ignored.
2. Click File | Export | MD5 Animation in the main menu.
3. To avoid reorienting your 3D assets to face positive X, clear the Reorient option. Normally, this option should be turned on, because unlike id tech 4, Blender assumes the "forward" direction for character rigs to be positive Y.
4. If you want a different scale for your 3D assets in the resulting file, use the Scale option.
5. Specify the file path and complete the export.

Batch Export of MD5 Meshes and Animations

Batch export relies on timeline markers. Based on pairs of matching markers, the exporter determines the frame ranges and assigns .md5anim file names. To tag some frames for export, put a marker with a name that ends in "_start" at the first frame of the animation fragment and another tag with a matching name ending in "_end" at its last frame. For example, a walk cycle would be tagged by markers named "walk_start" and "walk_end". If your scene contains multiple characters, consider prepending prefixes to marker names; for example: "demon_attack_start" and "demon_attack_end". This enables you to use the Marker filter parameter of the exporter (by entering "demon").

Notes:

• Interestingly, the names of timeline markers are not necessarily unique in Blender. Please avoid duplicate marker names. They will not make the script crash, but only one of the duplicates will be used in matching, and the results may not be what you expect.
• If no matching tagged ranges are found, the script defaults to exporting the current playback range.

1. Select one or more meshes that you want to export. The meshes should be associated with the same deforming armature. Any selected meshes that do not have an armature modifier will be ignored.
2. Click File | Export | MD5 (batch export) in the main menu.
3. To specify only a subset of the animation fragments present in the scene, type a prefix in the Marker filter text box.
4. To avoid reorienting your 3D assets to face positive X, clear the Reorient option. Normally, this option should be turned on, because unlike id tech 4, Blender assumes the "forward" direction for character rigs to be positive Y.
5. If you want a different scale for your 3D assets in the resulting file, use the Scale option.
6. Specify the .md5mesh file path; .md5anim files will be named after the markers that tag their frame ranges. Complete the export.

Handling Shaders

The add-on associates shader names in .md5mesh files with the names of materials on meshes. It doesn’t matter to the exporter what the material itself is like; only the name matters.
During import, a material is added to a mesh’s first material slot with the exact name of the shader, for example "models/monsters/mutant/teeth".
During export, the exact material name from the first non-empty material slot is used as the shader name. If there are no materials on a mesh, the name "default" is exported.

Export Errors

The script can detect a few situations where MD5 export is not possible, and pops up an error message instead of the file selector if any of them occurs. If you launched Blender from a terminal, the error message is duplicated there.

The following problems are reported:

• No armature-deformable meshes in the selection
• The selected meshes are deformed by more than one armature
• No deforming armature is associated with the selection
• The deforming armature has no bones in the reserved layer
• One or more exportable bones have parents outside the reserved layer
• Multiple root bones
• Vertices without deformation weights
• Vertices with deformation weights set to zero
• No UV coordinates in a mesh

The last three checks are not done for individual .md5anim export. This lets you use meshes that have these characteristics (for example, if you want custom bounds in your animation).

For problem-free export, address the above issues in advance.